Agent skills, an llms.txt API index, and the defects verifying them uncovered by obiot · Pull Request #1620 · melonjs/melonJS

obiot · 2026-08-30T09:47:51Z

Ships melonJS's guidance for AI coding assistants, and fixes the six code defects that verifying it against the source turned up.

Skills

23 task-oriented guides at packages/melonjs/skills/, versioned with the engine so the guidance always matches the release in node_modules. Each covers one subsystem and ends with a symptom → cause table, because melonJS's characteristic failure is silent rather than fatal — the engine warns once and degrades, so what the user sees is wrong output, not a stack trace.

Claude Code: /plugin marketplace add melonjs/melonJS (manifests in .claude-plugin/, claude plugin validate --strict passes)
Codex / Cursor / Gemini CLI: skills/AGENTS.md ships ready to copy into a game's project root
melonjs/SKILL.md is a router — an agent reads it, then the one or two guides it points at, not all 23

`llms.txt`

scripts/generate-llms-txt.ts runs after typedoc in pnpm doc, so the docs workflow publishes an index of every exported symbol at https://melonjs.github.io/melonJS/llms.txt. It is the escape hatch for anything the skills do not cover.

It reads the same TSDoc the reference pages render, so it cannot drift from them. Two details that took iteration: deprecated entries are marked, since those are precisely what a model trained on older melonJS reaches for; and the 50 String.prototype pages typedoc emits for the loader.nocache string are skipped, because indexing them would tell an agent that loader.nocache.trimEnd is part of the melonJS API. (Those pages are still in the published reference — a separate issue.)

Six defects, each proven by a failing test first

defect	proof before the fix
Tiled objects with no geometry got a triangular collision shape	`bodyDef.shapes[0].contains(4, 28)` → `false` for a 32×32 rect
`timer.setInterval` discarded its `pauseable` argument	stored `true` for `false`; never fired while paused — `setTimeout` passed the same test
loader error path read `this.onError` from a module function	detached `preload` rejected with `Cannot read properties of undefined (reading 'onError')`
`loader.onload` / `onProgress` / `onError` unsettable	assignment throws `TypeError` — the documented callback API was unusable
`input.preventDefault` unsettable	same, and no setter existed
Canvas `setBlendMode("none")` resolved by fall-through	now explicit, with the reason stated where the switch is read

The Tiled one is the most consequential: (0,0), (w,0), (w,h) omits the fourth vertex, so the lower-left half of every plain rectangular object in every map was not solid. Walk into it from the left and you pass through.

Two are removals rather than repairs. loader.onload / onProgress / onError were let bindings on an ES module namespace — assigning them always threw, so the migration path documented since 18.2.0 never worked for anyone, and loader.js's onProgress branch was dead code. input.preventDefault went the other way and gained setPreventDefault(), since it is a live option the engine reads rather than a deprecated one.

API reference corrected against the code

The same verification pass found the docs disagreeing with the source in 30 places. The rule applied throughout: where JSDoc and code disagree, the code wins and the doc changes — except timer.ts, where the code was the defect.

Renderable#draw told you to draw at (0, 0); preDraw never translates to this.pos
the body @example called viewport.follow(this.pos, …), which throws
Camera3d documented a roll axis that does not exist
Mesh omitted eight constructor settings, including lit — the switch for the whole lit-mesh path
the Asset typedef advertised "tmj" / "tsj" types that throw (extensions, not types)
Body#addShape's documentation had drifted onto a private helper, leaving the public method undocumented
18 effect classes carried an unresolvable @param import path, and 33 examples across 20 files taught renderable.shader =, deprecated since 19.2.0

The wiki carried three of the same errors and is already fixed (a24ab3e, 6e168f7) — two of them were where the engine's own JSDoc got them from.

Housekeeping

melonjs → 20.3.0, so the built version export, console header and plugin.register gate match the unreleased line
release.ts now aborts before tagging if .claude-plugin/plugin.json has drifted from it
root tsconfig.json gains types: ["node"] — scripts/ had 8 pre-existing type errors because node built-ins were unresolved, invisible to CI since turbo test:types only runs inside packages

Verification

6431 tests passing (264 files, 0 failures) · eslint 0 errors · biome clean · tsc clean · typedoc 0 errors · claude plugin validate --strict passes · npm pack ships all 23 skills plus AGENTS.md

Closes #1619

🤖 Generated with Claude Code

https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N

…ncovered Ship 23 task-oriented skills at `packages/melonjs/skills/`, versioned with the engine and installable in Claude Code as a plugin. Each covers one subsystem and ends with a symptom-to-cause table, because melonJS's characteristic failure is silent rather than fatal: the engine warns once and degrades, so wrong output — not a stack trace — is what the user sees. `AGENTS.md` ships alongside them for agents following that convention (Codex, Cursor, Gemini CLI), to copy into a game's project root. Add `scripts/generate-llms-txt.ts`, chained onto `pnpm doc`, publishing an index of every exported symbol at melonjs.github.io/melonJS/llms.txt — the escape hatch for anything the skills do not cover. It reads the same TSDoc the reference pages render, so it cannot drift; marks deprecated entries, which are exactly what a model trained on older melonJS reaches for; and skips the 50 `String.prototype` pages typedoc emits for the `loader.nocache` string, which would otherwise present `loader.nocache.trimEnd` as melonJS API. Verifying the skills against the source found six code defects. Each is fixed with a test written to fail first: - Tiled: an object with no explicit geometry got a *triangular* collision shape — `(0,0), (w,0), (w,h)` omits the fourth vertex, so the lower-left half of every plain rectangle in a map was not solid. - Timer: `setInterval`'s `pauseable` argument was discarded by `pauseable === true || true`, so no repeating timer could survive a pause. `setTimeout` was unaffected (#1619). - Loader: the error path read `this.onError` from a module function, which has no `this` — a detached `preload` reported "Cannot read properties of undefined" instead of the real load failure. - Loader: `onload` / `onProgress` / `onError` are removed. Deprecated since 18.2.0, they were `let` bindings on a module namespace, so assigning them always threw; the documented migration path never worked, and the branch guarding `onProgress` was dead code. - Input: `preventDefault` is documented as a global option but is read-only for the same reason. `setPreventDefault()` is the working form. - Canvas: `setBlendMode("none")` resolves to `"normal"` explicitly rather than by fall-through — there is no `globalCompositeOperation` that disables blending for the drawn area alone. The same pass corrected the API reference against the code it documents: `Renderable#draw` told you to draw at `(0, 0)` when `preDraw` never translates to `this.pos`; the `body` example called `viewport.follow(this.pos, …)`, which throws; `Camera3d` documented a `roll` axis that does not exist; `Mesh` omitted eight constructor settings including `lit`; the `Asset` typedef advertised `"tmj"` / `"tsj"` types that throw; `Body#addShape`'s documentation had drifted onto a private helper; and 18 effect classes carried an unresolvable `@param` import path plus examples teaching `renderable.shader =`, deprecated since 19.2.0. Also: bump melonjs to 20.3.0 so the built `version` matches the unreleased line, guard the plugin manifest against drifting from it in `release.ts`, and give the root tsconfig `types: ["node"]` so `scripts/` type-checks at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N

Copilot